<h1 id="versioning">Versioning</h1>

<h2 id="semantic-versioning">Semantic versioning</h2>

<p>Duktape follows <a href="http://semver.org/">Semantic Versioning</a> for
official releases:</p>
<ul>
<li>Major version changes when API incompatible changes are made.</li>
<li>Minor version changes when backwards-compatible functional changes are made.</li>
<li>Patch version changes when backwards-compatible bug fixes are made.</li>
</ul>

<p>The "public API" to which these rules apply include:</p>
<ul>
<li>The Duktape API calls documented on duktape.org; except those tagged
    <code>experimental</code>.</li>
<li>The global environment visible to ECMAScript code, including the <code>Duktape</code>
    object and other ECMAScript extensions, as documented on duktape.org;
    except changes needed to align with latest ECMAScript specifications.</li>
</ul>

<p>The following are not part of the "public API" versioning guarantees:</p>
<ul>
<li>Duktape API calls tagged <code>experimental</code>, and any other features
    documented as experimental.</li>
<li>Internal calls made by API macros.  While API calls implemented as macros
    are part of the public API, any internal calls the macros make are not,
    even if their symbol visibility is public.</li>
<li>Changing an API call from a function call to a macro (or vice versa).
    These are considered compatible changes (but are not done in patch releases).</li>
<li>Aligning with latest ECMAScript specifications.  Duktape tracks the latest
    ECMAScript specification (currently ES2016).  Backwards incompatible changes
    required to align with the latest specifications may be done in minor
    versions too (but not in patch versions unless necessary to fix a bug).
    Typically such changes are relatively minor, for example argument coercion
    or property inheritance changes.</li>
<li>Specific behavior which is explicitly noted to potentially change even in
    minor versions, for example:
    <ul>
    <li>Behavior of buffer objects when their backing buffer is smaller than
        the apparent size of the buffer object.  Memory safe behavior is
        guaranteed, but otherwise behavior may vary between versions.</li>
    </ul>
</li>
<li>Duktape config options.  Incompatible config option changes are not made in
    patch releases, but can be made in minor releases.  The goal is to cause a
    compile error (if possible) when a no-longer-supported feature option is
    used so that any incorrect assumptions can be fixed.</li>
<li>Extras distributed with Duktape (<code>extras/</code> directory).</li>
</ul>

<p>When a patch version is released, the following things are guaranteed:</p>
<ul>
<li>API binary compatibility is maintained: constant values don't change, function
    typing doesn't change, API call function/macro status doesn't change.</li>
<li>Bytecode dump/load format doesn't change so that you can load bytecode
    dumped from an older version which only differs in patch version.</li>
<li>ECMAScript semantics fixes are not included unless necessary to fix
    a bug.</li>
<li>Config options won't change in an incompatible manner.</li>
</ul>

<p>Development builds made from Duktape repo are not official releases and
don't follow strict semantic versioning.</p>

<h2 id="experimental-features">Experimental features</h2>

<p>Some new features and API calls are marked <b>experimental</b> which means
that they may change in an incompatible way even in a minor release.<p>

<p>Features may be marked experimental e.g. because they are useful but
incomplete, or because the best design is not obvious and it's useful to
gather some feedback before committing to the design.  Typically a feature
is experimental for one minor release and then, after the necessary changes,
becomes a fully supported feature.</p>

<h2 id="version-naming">Version naming</h2>

<p>Releases use the form <i>(major).(minor).(patch)</i>, e.g. <b>1.0.3</b>.</p>

<h2>DUK_VERSION and Duktape.version</h2>

<p><code>DUK_VERSION</code> and <code>Duktape.version</code> provide version
identification using a single number computed as:
<code>(major * 10000 + minor * 100 + patch)</code>,
then subtracting one for development builds (not official releases) made from
Duktape repo.</p>

<p>Note the limitations for development builds:</p>
<ul>
<li>Development builds for the same upcoming release are not distinguished from
    one another: for example, all builds from master prior to 1.3.0 release
    are identified as 10299.</li>
<li>Development builds for patch releases are not distinguished from the
    previous patch release: for example, a development build after 1.3.2 but
    before 1.3.3 is identified as 10302.</li>
</ul>

<p>Development builds shouldn't be used in production, but the current
<code>DUK_VERSION</code> and <code>Duktape.version</code> number provides
a useful approximation for version comparison: a development build will
compare smaller than the actual release, but higher (or equal) than a
previous release.</p>

<h2 id="versioning-examples">Examples</h2>

<p>The table below provides some examples, in ascending version order:</p>
<table>
<tr>
<th>Version</th>
<th>DUK_VERSION &amp;<br />Duktape.version</th>
<th>Notes</th>
</tr>
<tr><td>0.12.0</td><td>1200</td><td></td></tr>
<tr><td>1.0.0</td><td>10000</td><td></td></tr>
<tr><td>1.2.99</td><td>10299</td><td>Development build before 1.3 release.</td></tr>
<tr><td>1.3.0</td><td>10300</td><td></td></tr>
<tr><td>1.3.2</td><td>10302</td><td></td></tr>
<tr><td>2.0.0</td><td>20000</td><td></td></tr>
</table>

<h2 id="version-maintenance">Maintenance of stable versions</h2>

<p>There's no long term maintenance policy yet: stable versions will get bug
fixes (patch releases) at least until the next stable version has been
released, and there has been some time to migrate to it.</p>

<h2>Incompatible changes</h2>

<p>The general goal for incompatible changes is that an application relying
on old, unsupported features will fail to build.  It is preferable to have the
build fail rather than to be silently broken.  This means for example that:</p>
<ul>
<li>When API call semantics are changed, the old API call is removed (causing
    a build failure if used) and a new one is added.</li>
<li>When support for an old feature option is removed, an attempt to use it
    will cause a build failure.</li>
</ul>

<p>This is not a hard rule, and it cannot be achieved in all cases.</p>
